All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class sun.security.AuthContext

java.lang.Object
   |
   +----java.util.Dictionary
           |
           +----sun.security.AuthContext

public class AuthContext

extends Dictionary

Examples of the kind of information which may be held, on behalf of a principal, in an Authentication Context, include:

• Private keys and their associated public key certificate chains, used to authenticate principals in public key authentication schemes such as X.509.
• Passwords, passphrases, or other kinds of shared secrets used to authenticate users. A "single logon" policy is supported (so that several subsystems share authentication data), but not mandated.
• Objects used for trust management.
• A trusted path to a user, which may be used to interactively authenticate that user or establish trust policy. For example, users may interact via GUI or TTY-style devices, or might in the future interact through hardware tokens such as smart cards.
• Subsystem-specific state derived from private or secret keys, which may be independently used to authenticate. For example, it is common to use expensive public key algorithms to exchange secrets, which are subsequently used with more efficient shared-key algorithms.

---

Programming Model

Data is identified by an index, which acts as a capability for accessing data provided by a java.util.Dictionary which has most operations disabled. No code module can just ask for all of the indices in a context. Modules must learn the right indices, either by defining some indices themselves or through some relationship with another module where trust is extended by exposing the index.

Both authentication contexts and the indices to them should be treated as sensitive data; indices more so. Some security risks are as follows:

• Indices should normally be treated as secrets, since each process has one authentication context (the "default" context) which is widely accessible. Data associated with non-secret indices within that context can not be kept secret.
• Processes with multiple contexts should be careful not to share them between components when that would be inappropriate. For example, a thread group working exclusively on behalf of one principal should not be given another principal's context, lest it make an action on behalf of that other principal by accident.
• Passing data from contexts between processes should only be done with extreme caution, since that can allow "unconstrained delegation" to happen. Once a process controlled by an adversary gets that delegation, they will usually be able to masquerade as some principal without having been authorized. (Contexts can't be passed between processes, but trusted subsystems might take data from a context and use it in an inappropriate manner.)

---

Indices

Knowledge of an index provides access to the data held in a context. The model is the classic "capability" model, constrained so that the caller must also have access to the authentication context holding the data in question. The lifecycle of an index is:

1. Indices are created by an arbitrary code module, such as a class within a package.
2. At some point, a value is associated with that index within the scope of a given context. Some such associations are established at the time the context is initialized; others are established later.
3. Indices are then exchanged among modules which have explicit reasons to trust each other. For example,
   • Many packages implicitly trust all their classes, and would be able to save an index as package-private data. For example, any class in the package might access some passphrase-protected data that the class manipulates.
   • Other packages only trust a few internal classes, and would save an index as class-private data with very selective sharing. Continuing with the example above, not all classes would have access to that passphrase.
   • Several "system" modules might trust each other well, and share indices with each other. There is a default passphrase index defined, to which access is controlled by using a security manager test.
   • Some authentication data might not be at all sensitive, and indices for such data would be public knowledge. For example, various identifiers for the logged-in user would normally be freely shared ... a user name on Windows or UNIX, or a user ID.
4. Code modules access data by presenting the associated index to a given authentication context. A given index will, as a rule, be associated with context-specific data. It is this feature which allows subsystems to authenticate on behalf of different entities; the subsystem only uses one set of indices.
5. Accessing data identified by some indices may involve using I/O calls, for example for determining a passphrase or accessing private keys held in secure storage.

NOTE: Since JDK 1.1 garbage collects classes, processes need to explicitly hold on to the default AuthContext to prevent the security data from being garbage collected. Just save it as private state in the class holding main(). In the future, the JDK will hold on to this default context more firmly.

AuthContext()

Constructs the common authentication context infrastructure.

elements()

An unsupported java.util.Dictionary method.

get(Object)

Retrieves subsystem-specific authentication data.

getDefault()

Return the default authentication context used by this process.

getPassphraseIndex()

Returns the "well known" index in the authentication context which provides access to a plaintext passphrase.

getTrustDecider()

Returns the TrustDecider object used by this authentication context.

isEmpty()

Returns true iff the context size is zero.

keys()

An unsupported java.util.Dictionary method.

put(Object, Object)

Stores subsystem-specific authentication data.

remove(Object)

An unsupported java.util.Dictionary method.

setDefault(AuthContext)

Sets the process default authentication context.

setTrustDecider(TrustDecider)

Assigns the TrustDecider object used by this authentication context.

size()

Returns the number of entries in the context.

trustedGet(Object)

Provides a simple "Secure path" facility.

 protected AuthContext()

Constructs the common authentication context infrastructure. Different subclasses of authentication contexts may exist; for example, ones using a local Graphical User Interface (GUI), or ones using command-line style interaction (for cases where remotable GUIs are not available).

 public static void setDefault(AuthContext context)

Sets the process default authentication context. This is effective only if the context has not already been assigned, and if the context is non-null. Normally, process startup establishes this default, and arranges that a reference to that default be "kept live" outside of this class (so that the security data is not garbage collected inappropriately).

Parameters:

context - the intended process default authentication context

 public static AuthContext getDefault()

Return the default authentication context used by this process. Processes may have access to multiple authentication contexts, if they have been trusted to act on behalf of multiple principals. However, only one of those will be its own default context.

In the future, it will probably be possible to stack the default authentication context being used by a thread for a series of operations, arranging that the thread-default context be restored to its previous value when leaving a particular stack frame. This model is known to be important for several classes of server style applications.

At this time, a very simple access control policy is defined for access to this context: if a security manager is available, accessing the authentication context is treated as equivalent to accessing system properties. In the future, this policy will be improved; the authentication context seems like it should be part of the security context.

Returns:

the process default authentication context

 public int size()

Returns the number of entries in the context.

Overrides:

size in class Dictionary

 public boolean isEmpty()

Returns true iff the context size is zero.

Overrides:

isEmpty in class Dictionary

 public Enumeration keys()

An unsupported java.util.Dictionary method. The method is not supported since the indices for the elements are treated as capabilities, and are intentionally hidden from most code which has access to the authentication context.

Overrides:

keys in class Dictionary

 public Enumeration elements()

An unsupported java.util.Dictionary method. The method is not supported since the data elements are only exposed to callers who have the correct index/capability.

Overrides:

elements in class Dictionary

 public Object remove(Object index)

An unsupported java.util.Dictionary method. The method is not supported since the security policy implications of deleting (or expiring) authentication data are not well understood.

Overrides:

remove in class Dictionary

 public final Object put(Object index,
                         Object element)

Stores subsystem-specific authentication data. Note that this data will be visible between subsystems only if they share the index used to access this data, or otherwise explicitly allow that visibility.

Currently, if the index already has a value, nothing is changed. Later versions may allow values to be changed by appropriately authorized entities.

Parameters:

index - used to identify the specific data

element - data being stored

Returns:

null

Overrides:

put in class Dictionary

 public final Object get(Object index)

Retrieves subsystem-specific authentication data. Unless two subsystems share the key used to access this data, only the subsystem which stored the data (and remembered its index) can retrieve it. That is, the index is used as a capability to grant access to a secret whose value differs in different contexts, but whose index remains the same.

Parameters:

index - used to identify the specific data

Returns:

element stored under that index

Overrides:

get in class Dictionary

 public final void setTrustDecider(TrustDecider decider)

Assigns the TrustDecider object used by this authentication context. This implements a trust policy -- that is, what entities are trusted for specific purposes, in particular different authentication roles.

Parameters:

decider - encapsulates the trust policy

 public final TrustDecider getTrustDecider()

Returns the TrustDecider object used by this authentication context. This is used to identify what entities are trusted for specific purposes.

Returns:

the TrustDecider encapsulating the trust policy used by this authentication context

 public static Object getPassphraseIndex()

Returns the "well known" index in the authentication context which provides access to a plaintext passphrase. This passphrase is used in various authentication protocols, and to gain access to encrypted private keys. That is, this index supports a "single signon" model.

This "single signon" model is optional. Other indices may be recognized by the trustedGet module as requesting prompts for additional passphrases, for subsystems which have policies preventing reuse of passphrases.

Returns:

the index of the (plaintext) passphrase used to support the "single signon" model.

See Also:

trustedGet

 protected Object trustedGet(Object index)

Provides a simple "Secure path" facility. This is used to acquire some kinds of data which require device interaction. Examples include prompting users for passphrases. Eventually, interaction with devices such as "smart cards" to acquire access to keys, or with networked policy servers, could fit in this framework.

At this time, this routine is called to return any value which are is already stored in the authentication context, and the result of that call is then stored in the context.

Subclasses are expected to provide their own implementations of trusted path facilities, for example ones using terminal I/O, a window system, smart cards, and other hardware devices based on the particular index which was requested.

Parameters:

index - the index for the value which is to be acquired using some trusted path interaction.

All Packages  Class Hierarchy  This Package  Previous  Next  Index